home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 16 / AMIGAplus Sonderheft 16 (1998)(ICP)(DE)[!].iso / pd / anwendungen / xpk_develop / autodocs / xpksub.doc < prev    next >
Text File  |  1998-08-27  |  10KB  |  286 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpksub.library/XpksPackerInfo
  4. xpksub.library/XpksPackChunk
  5. xpksub.library/XpksPackFree
  6. xpksub.library/XpksPackReset
  7. xpksub.library/XpksUnpackChunk
  8. xpksub.library/XpksUnpackFree
  9. xpksub.library/--sublibs--
  10.  
  11. xpksub.library/XpksPackerInfo
  12.  
  13.     NAME
  14.         XpksPackerInfo - Get information about a packer sub-library
  15.  
  16.     SYNOPSIS
  17.         info = XpkPackerInfo()
  18.          D0
  19.  
  20.         struct XpkInfo *XpkPackerInfo(void);
  21.  
  22.     FUNCTION
  23.         Returns all information about a packer sub-library for use
  24.         by the master library.
  25.  
  26.     RESULT
  27.         info - pointer to struct XpkPackerInfo. see xpk/xpksub.h
  28.                for the meaning of all the fields.
  29.  
  30.     SEE ALSO
  31.         XpksPackChunk()
  32.  
  33. xpksub.library/XpksPackChunk
  34.  
  35.     NAME
  36.         XpksPackChunk - Pack a chunk of data
  37.  
  38.     SYNOPSIS
  39.         err = XpksPackChunk( param )
  40.         D0                    A0
  41.  
  42.         LONG XpksPackChunk(struct XpkSubParams *);
  43.  
  44.     FUNCTION
  45.         Packs one chunk of data from memory to memory. The size of the 
  46.         chunk will not surpass the MaxPkInChunk field of the packer info
  47.         structure. Chunks are numbered in case a library writes various
  48.         dictionaries at special places.
  49.  
  50.     INPUTS
  51.         struct XpkSubParams, where the fields mean:
  52.           InBuf     Pointer to the data to be compressed
  53.           InLen     The number of bytes to pack
  54.           OutBuf    Pointer to the memory area to write packed data to
  55.           OutBufLen Size of above memory area
  56.           OutLen    Will be set to compressed length by sublib
  57.           Number    The number of this chunk
  58.           Mode      The sub-mode to be used
  59.           Password  The password to be used for encryption
  60.           Sub[4]    Here the sub library stores its private data
  61.  
  62.     RESULTS
  63.         err    - global xpk error code
  64.         OutLen - Number of bytes written
  65.  
  66.     SEE ALSO
  67.         XpksPackReset(), XpksPackFree()
  68.  
  69. xpksub.library/XpksPackFree
  70.  
  71.     NAME
  72.         XpksPackFree - Free buffers associated with packing process
  73.  
  74.     SYNOPSIS
  75.         XpksPackFree( param )
  76.                        A0
  77.  
  78.         void XpksPackFree(struct XpkSubParams *)
  79.  
  80.     FUNCTION
  81.         Frees all buffers the sub-library has allocated privately
  82.         while doing some packing
  83.  
  84.     INPUTS
  85.         param - The XpkSubParams used for packing
  86.  
  87.     SEE ALSO
  88.         XpksPackChunk(), XpksPackReset()
  89.  
  90. xpksub.library/XpksPackReset
  91.  
  92.     NAME
  93.         XpksPackReset - Clears all state information
  94.  
  95.     SYNOPSIS
  96.         XpksPackReset( param )
  97.                         A0
  98.  
  99.         LONG XpksPackReset(struct XpkSubParams *)
  100.  
  101.     FUNCTION
  102.         Clears all internal tables and any other state information of the
  103.         packer. This has the effect, to guarantee independent unpacking
  104.         of the chunk to come. The packers call this function automatically
  105.         before returning XPKERR_EXPANSION (data could not be compressed).
  106.  
  107.         Note:   packers have to store all of their state relevant to packing
  108.                 in XpkSubParams to ensure reentrantness.
  109.  
  110.     INPUTS
  111.         param - The XpkSubParams used for packing
  112.  
  113.     SEE ALSO
  114.         XpksPackChunk(), XpksPackFree()
  115.  
  116. xpksub.library/XpksUnpackChunk
  117.  
  118.     NAME
  119.         XpksUnpackChunk - Uncompress a chunk of data
  120.  
  121.     SYNOPSIS
  122.         err = XpksUnpackChunk( param )
  123.                                 A0
  124.  
  125.         LONG XpksUnpackChunk(struct XpkSubParams *)
  126.  
  127.     FUNCTION
  128.         Decompresses one chunk of data.
  129.  
  130.     INPUTS
  131.         param - The XpkSubParams used for unpacking
  132.           xsp_InBuf     Pointer to the data to be uncompressed
  133.           xsp_InLen     The number of bytes to unpack
  134.           xsp_OutBuf    Pointer to the memory area to write unpacked data to
  135.           xsp_OutBufLen Size of above memory area
  136.           xsp_OutLen    Must contain the decompressed size of the data
  137.           xsp_Number    The number of this chunk
  138.           xsp_Password  The password to be used for decryption
  139.           xsp_Sub[4]    Here the sub library stores its private data
  140.         
  141.  
  142.     RESULT
  143.         err - global xpk error code
  144.  
  145.     SEE ALSO
  146.         XpksUnpackFree()
  147.  
  148. xpksub.library/XpksUnpackFree
  149.  
  150.     NAME
  151.         XpksUnpackFree - Free all private data the sublib has allocated
  152.  
  153.     SYNOPSIS
  154.         XpksUnpackFree( param )
  155.                           A0
  156.  
  157.         LONG XpksUnpackFree( struct XpkSubParams * )
  158.  
  159.     FUNCTION
  160.         Will free all memory the sub-library has allocated during the
  161.         decompression.
  162.  
  163.     INPUTS
  164.         param - The XpkSubParams used for unpacking
  165.  
  166.     SEE ALSO
  167.         XpksUnpackChunk()
  168.  
  169. xpksub.library/--sublibs--
  170.  
  171. Some remarks for sublib writers
  172. -------------------------------
  173.  
  174. First of all, Read the documentation. If you have got any further questions
  175. writing xpksublibraries, either contact one of the XPK maintainers.
  176.  
  177. The name of a sub library is xpkXXXX.library, where XXXX is a combination
  178. of uppercase characters ('A' to 'Z') and numbers ('0' - '9').
  179. The first character must not be a 'X' (xpkXTRA.library is not allowed), as
  180. this letter is reserved for xex libraries.
  181.  
  182. How XpkPackChunk works:
  183. - Check xpar->xsp_Sub[0]. If it is 0, this is the first call. Allocate your
  184.   tables and store pointers to them in xsp_Sub[0] .. xsp_Sub[3].
  185. - Read xpar->xsp_InLen bytes from xpar->xsp_InBuf and pack them to
  186.   xpar->xsp_OutBuf. Do not exceed xpar->xsp_OutBufLen. Store packed len in
  187.   xpar->xsp_OutLen.
  188.  
  189. How XpkUnpackChunk works:
  190. - Check xpar->xsp_Sub[0]. If it is 0, this is the first call. Allocate your
  191.   tables and store pointers to them in xsp_Sub[0] .. xsp_Sub[3].
  192. - Read xpar->xsp_InLen bytes from xpar->xsp_InBuf and unpack them to
  193.   xpar->xsp_OutBuf. Do noot exceed xpar->xsp_OutBufLen. Maybe compare
  194.   uncompressed len with xpar->xsp_OutLen.
  195.  
  196. Other notes:
  197. - Your library should, of course, be re-entrant. This means no PC-relative
  198.   addressing of writeable data. Whatever you have, store a pointer to it
  199.   somewhere in the XpkSubMessage. In short: All state information of the
  200.   sublib is in the XpkSubMessage. You can detect the first chunk of a file
  201.   by the fact that this pointer is still NULL. In case your lib is not
  202.   re-entrant, return XPKERR_LIBINUSE when required.
  203.  
  204. - There will be no larger chunks on (de)compression than the first one.
  205.  
  206. - On compression, you may expand the data by XPK_MARGIN bytes maximum. This
  207.   means the output buffer is as large as the input buffer plus XPK_MARGIN.
  208.   Compression libs would, of course, already return XPKERR_EXPANSION if
  209.   they exceed the input buffer.
  210.  
  211. - You must supply a function XpkPackReset, which clears all tables so
  212.   that the next chunk will be able to be unpacked independently. You also
  213.   have to reinitialize all state information [calling your XpkPackReset]
  214.   before returning XPKERR_EXPANSION!
  215.  
  216. - On decompression, you will also have a XPK_MARGIN byte saftey margin for
  217.   runaway unpacking. 
  218.  
  219. - Fill in one XpkInfo structure. See xpk/xpksub.h for the meanings of
  220.   the fields therein.
  221.  
  222. - If your packer has only one packing mode, fill in one XpkMode structure 
  223.   (see xpk.h). Set the 'xm_Upto' field to 100, this means this struct
  224.   handles  all modes up to (and including) 100, which is the max packing
  225.   mode. Place a pointer to this struct in the XpkInfo structure.
  226.  
  227. - There must be at least one XpkMode structure, and the last XpkMode 
  228.   structure must have the xm_Upto set to 100. It must!
  229.  
  230. - If your packer has several modes, create several XpkMode structures and
  231.   sort them by efficiency in ascending order. Place a pointer to them
  232.   in XpkInfo. Set the XPKIF_MODES flag in the xi_Flags field of XpkInfo.
  233.  
  234. - Your packer will get the 0..100 number and is responsible of mapping
  235.   it to its own packing modes.
  236.  
  237. - Set the xi_DefMode field to some 0...100 number.
  238.  
  239. - If XSF_STEPDOWN is set in the xsp_Flags field of the SubParams structure,
  240.   you are allowed to reduce packing efficiency in order to save mem.
  241.  
  242. - Encryption libraries should compute a cryptographic hash [that is a
  243.   checksum] while or after decryption and compare it with one stored in the
  244.   encrypted data. If the hash of the decrypted text does not match the
  245.   stored checksum, return XPKERR_WRONGPW. Note, that this hash inevitably
  246.   discloses information applicable to breaking the code. Try to keep this
  247.   information small, e.g. by using a 16bit hash. Take care, that one has to
  248.   decrypt the whole chunk before it is possible to compute the hash of the
  249.   decrypted data.
  250.  
  251. How to get values for xm_PackSpeed, xm_UnpackSpeed, xm_Ratio?
  252. -------------------------------------------------------------
  253. Older versions of xpkmaster.library defined an Amiga A3000/25 with SCRAM
  254. and AmigaVision executable as standard test for pack algorithms.
  255.  
  256. I searched for better testing defines and defined a new system which should
  257. be used now and in future:
  258.  
  259. At http://corpus.canterbury.ac.nz/ you find a big set of files called
  260. "Canterbury Corpus". (Not the large one, but standard test archive). This
  261. is a collection of standard test files which can be used to test the
  262. packing algorithms.
  263.  
  264. Speed values are still a problem, as it is hard to get a value usable on
  265. all machines. New values should be computed on an A4000 with 68060/50Mhz
  266. with no startup-sequence bootup. This defines a big field of different
  267. machines which differ in RAM size, bus speed and other parameters, but the
  268. test must be usable and so I cannot define one special environment.
  269.  
  270. The values entered in XpkMode structure are a sum of all test files.
  271. You need to pack all files and note their results (reached file size,
  272. crunch time, decrunch time). Use xBench to do that, as this is very
  273. accurate (as good as possible).
  274.  
  275. Now add input file size (INSIZE), crunched file size (CRSIZE), needed
  276. crunch time (CRTIME) and needed uncrunch time (UNCRTIME) for all of the
  277. standard test files!
  278.  
  279. xm_Ratio    = 1000*(1-(CRSIZE)/(INSIZE))
  280. xm_PackSpeed    = INSIZE/1024/CRTIME
  281. xm_UnpackSpeed    = INSIZE/1024/UNCRTIME
  282.  
  283. When you do not own an A4000 with 68060 CPU at 50Mhz then try to adapt
  284. speed values.
  285.  
  286.